@material/react-ripple

✨ Are you a part of the Material Design web community? Help us improve by filling out this 10 minute survey. ✨

React Ripple

A React version of an MDC Ripple.

Installation

npm install @material/react-ripple

Usage

Styles

with Sass:

import '@material/react-ripple/index.scss';

with CSS:

import '@material/react-ripple/dist/ripple.css';

Javascript Instantiation

To wrap a component with the ripple HOC, please follow this example:

import withRipple from '@material/react-ripple';

const Icon = (props) => {
  const {
    children,
    className = '',
    // You must call `initRipple` from the root element's ref. This attaches the ripple
    // to the element.
    initRipple,
    // include `unbounded` to remove warnings when passing `otherProps` to the
    // root element.
    unbounded,
    ...otherProps
  } = props;

  // any classes needed on your component needs to be merged with
  // `className` passed from `props`.
  const classes = `ripple-icon-component ${className}`;

  return (
    <div
      className={classes}
      ref={initRipple}
      {...otherProps}>
      {children}
    </div>
  );
};

const RippleIcon = withRipple(Icon);

Wrap your Icon component with the HOC withRipple, which returns a component with a ripple capable surface.

Advanced Usage

Ripple surface and ripple activator

You may want to apply the visual treatment (CSS classes and styles) for a ripple surface on one element, but have its activation rely on a different element. For example, putting a ripple on a <div> which will be activated by focusing on a child <input> element. We call the visual element the "ripple surface" and the activating element the "ripple activator".

The initRipple callback prop can take in an extra activator argument for the case where the ripple activator differs from the ripple surface. If the activator argument is not provided, the ripple surface will also serve as the ripple activator.

import withRipple from '@material/react-ripple';

const MyInput = (props) => {
  const {
    rippleActivator,
    ...otherProps
  } = props;

  return (
    <input ref={rippleActivator} {...otherProps} />
  );
}

class MyComponent extends React.Component {
  rippleActivator = React.createRef();

  init = (el) => {
    this.props.initRipple(el /* surface */, this.rippleActivator.current /* activator */);
  }

  render() {
    const {
      className,
      initRipple,
      unbounded,
      ...otherProps
    } = this.props;

    return (
      <div
        className={`my-component ${className}`}
        ref={this.init}
        {...otherProps}>
        <MyInput rippleActivator={this.rippleActivator} />
      </div>
    );
  }
};

const MyRippledComponent = withRipple(MyComponent);

Props

Prop Name	Type	Description
unbounded	boolean	Ripple is unbounded if true.
disabled	n/a	Disables ripple if true.
style	object	Inline styles of root element.
className	string	Classes to appear on className attribute of root element.

Sass Mixins

Sass mixins may be available to customize various aspects of the components. Please refer to the MDC Web repository for more information on what mixins are available, and how to use them.

Advanced Sass Mixins

Changelog

0.6.2 (2018-11-07)

Bug Fixes

• checkbox: add focusable=false to svg for a11y (#375) (c7f3b97)
• drawer: update readme and screenshots to support below top app bar (#397) (90adbbe)
• infrastructure: increase screenshot timeout to decrease flakes (#373) (e96ca10)
• layout-grid: remove unit test console warnings (#379) (408cdd2)
• list: selectedIndex 0 isn't working (#387) (4e62aae)
• text-field: added reference to input element (#414) (ea04dc6)
• text-field: allow for input isValid override (#374) (7872856)
• text-field: put foundation on state and do render input unless foundation is present (#353) (2cb5d64)
• text-field: remove foundation.setValue call during onChange (#350) (36469f7)
• top-app-bar: add FixedAdjust to npmignore (#371) (d4ad675)
• top-app-bar: allow react elements in title (#376) (f6da361)

Code Refactoring

• list: Refactor list item management (#413) (1f563d3)

Features

• infrastructure: add verify pkg main to dist script (#320) (459c6dd)

BREAKING CHANGES

• list: Event handlers moved from list to list item. New props on list item for focus, follow href, toggle checkbox, and classnames/attributes passed down from list. Remove ID prop from list item.

<a name="0.6.0"></a>